home *** CD-ROM | disk | FTP | other *** search
EEEExxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333))))22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222EEEE))))xxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333)))) NNNNAAAAMMMMEEEE ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS perl -MExtUtils::Embed -e xsinit perl -MExtUtils::Embed -e ldopts DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ExtUtils::Embed provides utility functions for embedding a Perl interpreter and extensions in your C/C++ applications. Typically, an application MMMMaaaakkkkeeeeffffiiiilllleeee will invoke ExtUtils::Embed functions while building your application. @@@@EEEEXXXXPPPPOOOORRRRTTTT ExtUtils::Embed exports the following functions: _x_s_i_n_i_t(), _l_d_o_p_t_s(), _c_c_o_p_t_s(), _p_e_r_l__i_n_c(), _c_c_f_l_a_g_s(), _c_c_d_l_f_l_a_g_s(), _x_s_i__h_e_a_d_e_r(), _x_s_i__p_r_o_t_o_s(), _x_s_i__b_o_d_y() FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS xsinit() Generate C/C++ code for the XS initializer function. When invoked as `perl -MExtUtils::Embed -e xsinit --` the following options are recognized: ----oooo <output filename> (Defaults to ppppeeeerrrrllllxxxxssssiiii....cccc) ----oooo SSSSTTTTDDDDOOOOUUUUTTTT will print to STDOUT. ----ssssttttdddd (Write code for extensions that are linked with the current Perl.) Any additional arguments are expected to be names of modules to generate code for. When invoked with parameters the following are accepted and optional: xsinit($filename,$std,[@modules]) Where, $$$$ffffiiiilllleeeennnnaaaammmmeeee is equivalent to the ----oooo option. $$$$ssssttttdddd is boolean, equivalent to the ----ssssttttdddd option. [[[[@@@@mmmmoooodddduuuulllleeeessss]]]] is an array ref, same as additional arguments mentioned above. Page 1 (printed 10/23/98) EEEExxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333))))22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222EEEE))))xxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333)))) Examples perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket This will generate code with an xxxxssss____iiiinnnniiiitttt function that glues the perl SSSSoooocccckkkkeeeetttt::::::::bbbboooooooottttssssttttrrrraaaapppp function to the C bbbbooooooootttt____SSSSoooocccckkkkeeeetttt function and writes it to a file named "xsinit.c". Note that DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr is a special case where it must call bbbbooooooootttt____DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr directly. perl -MExtUtils::Embed -e xsinit This will generate code for linking with DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr and each static extension found in $$$$CCCCoooonnnnffffiiiigggg{{{{ssssttttaaaattttiiiicccc____eeeexxxxtttt}}}}. The code is written to the default file name ppppeeeerrrrllllxxxxssssiiii....cccc. perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle Here, code is written for all the currently linked extensions along with code for DDDDBBBBIIII and DDDDBBBBDDDD::::::::OOOOrrrraaaacccclllleeee. If you have a working DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr then there is rarely any need to statically link in any other extensions. ldopts() Output arguments for linking the Perl library and extensions to your application. When invoked as `perl -MExtUtils::Embed -e ldopts --` the following options are recognized: ----ssssttttdddd Output arguments for linking the Perl library and any extensions linked with the current Perl. ----IIII <path1:path2> Search path for ModuleName.a archives. Default path is @@@@IIIINNNNCCCC. Library archives are expected to be found as ////ssssoooommmmeeee////ppppaaaatttthhhh////aaaauuuuttttoooo////MMMMoooodddduuuulllleeeeNNNNaaaammmmeeee////MMMMoooodddduuuulllleeeeNNNNaaaammmmeeee....aaaa For example, when looking for SSSSoooocccckkkkeeeetttt....aaaa relative to a search path, we should find aaaauuuuttttoooo////SSSSoooocccckkkkeeeetttt////SSSSoooocccckkkkeeeetttt....aaaa When looking for DDDDBBBBDDDD::::::::OOOOrrrraaaacccclllleeee relative to a search path, we should find aaaauuuuttttoooo////DDDDBBBBDDDD////OOOOrrrraaaacccclllleeee////OOOOrrrraaaacccclllleeee....aaaa Keep in mind, you can always supply ////mmmmyyyy////oooowwwwnnnn////ppppaaaatttthhhh////MMMMoooodddduuuulllleeeeNNNNaaaammmmeeee....aaaa as an additional linker argument. Page 2 (printed 10/23/98) EEEExxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333))))22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222EEEE))))xxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333)))) -------- <list of linker args> Additional linker arguments to be considered. Any additional arguments found before the -------- token are expected to be names of modules to generate code for. When invoked with parameters the following are accepted and optional: ldopts($std,[@modules],[@link_args],$path) Where, $$$$ssssttttdddd is boolean, equivalent to the ----ssssttttdddd option. [[[[@@@@mmmmoooodddduuuulllleeeessss]]]] is equivalent to additional arguments found before the -------- token. [[[[@@@@lllliiiinnnnkkkk____aaaarrrrggggssss]]]] is equivalent to arguments found after the -------- token. $$$$ppppaaaatttthhhh is equivalent to the ----IIII option. In addition, when ldopts is called with parameters, it will return the argument string rather than print it to STDOUT. Examples perl -MExtUtils::Embed -e ldopts This will print arguments for linking with lllliiiibbbbppppeeeerrrrllll....aaaa, DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr and extensions found in $$$$CCCCoooonnnnffffiiiigggg{{{{ssssttttaaaattttiiiicccc____eeeexxxxtttt}}}}. This includes libraries found in $$$$CCCCoooonnnnffffiiiigggg{{{{lllliiiibbbbssss}}}} and the first ModuleName.a library for each extension that is found by searching @@@@IIIINNNNCCCC or the path specifed by the ----IIII option. In addition, when ModuleName.a is found, additional linker arguments are picked up from the eeeexxxxttttrrrraaaalllliiiibbbbssss....lllldddd file in the same directory. perl -MExtUtils::Embed -e ldopts -- -std Socket This will do the same as the above example, along with printing additional arguments for linking with the SSSSoooocccckkkkeeeetttt extension. perl -MExtUtils::Embed -e ldopts -- DynaLoader This will print arguments for linking with just the DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr extension and lllliiiibbbbppppeeeerrrrllll....aaaa. Page 3 (printed 10/23/98) EEEExxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333))))22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222EEEE))))xxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333)))) perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql Any arguments after the second '--' token are additional linker arguments that will be examined for potential conflict. If there is no conflict, the additional arguments will be part of the output. perl_inc() For including perl header files this function simply prints: -I$Config{archlibexp}/CORE So, rather than having to say: perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"' Just say: perl -MExtUtils::Embed -e perl_inc ccflags(), ccdlflags() These functions simply print $Config{ccflags} and $Config{ccdlflags} ccopts() This function combines _p_e_r_l__i_n_c(), _c_c_f_l_a_g_s() and _c_c_d_l_f_l_a_g_s() into one. xsi_header() This function simply returns a string defining the same EEEEXXXXTTTTEEEERRRRNNNN____CCCC macro as ppppeeeerrrrllllmmmmaaaaiiiinnnn....cccc along with #including ppppeeeerrrrllll....hhhh and EEEEXXXXTTTTEEEERRRRNNNN....hhhh. xsi_protos(@modules) This function returns a string of bbbbooooooootttt____$$$$MMMMoooodddduuuulllleeeeNNNNaaaammmmeeee prototypes for each @modules. xsi_body(@modules) This function returns a string of calls to nnnneeeewwwwXXXXSSSS(((()))) that glue the module bbbboooooooottttssssttttrrrraaaapppp function to bbbbooooooootttt____MMMMoooodddduuuulllleeeeNNNNaaaammmmeeee for each @modules. xxxxssssiiiinnnniiiitttt(((()))) uses the xsi_* functions to generate most of it's code. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS For examples on how to use EEEExxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd for building C/C++ applications with embedded perl, see the eg/ directory and the _p_e_r_l_e_m_b_e_d manpage. Page 4 (printed 10/23/98) EEEExxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333))))22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222EEEE))))xxxxttttUUUUttttiiiillllssss::::::::EEEEmmmmbbbbeeeedddd((((3333)))) SSSSEEEEEEEE AAAALLLLSSSSOOOO the _p_e_r_l_e_m_b_e_d manpage AAAAUUUUTTTTHHHHOOOORRRR Doug MacEachern <_d_o_u_g_m@_o_s_f._o_r_g> Based on ideas from Tim Bunce <_T_i_m._B_u_n_c_e@_i_g._c_o._u_k> and mmmmiiiinnnniiiimmmmoooodddd....ppppllll by Andreas Koenig <_k@_a_n_n_a._i_n-_b_e_r_l_i_n._d_e> and Tim Bunce. Page 5 (printed 10/23/98) 
